Apple WWDC 1996/WWDC96_1996 (CD).toast/Technology Materials/MacOS 8 Resources/Developer Tools/Mac OS 8 Interfaces & Libraries/Interfaces/AIncludes/FileManager.a

Text File | 1996-05-01 | 40.6 KB | 1,131 lines | [TEXT/MPS ]

;
;    File:        FileManager.a
;
;    Contains:    FileManager Interface
;
;    Version:    Technology:    System 8
;                Release:    Universal Interfaces 3.0d3 on Copland DR1
;
;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
;
;    Bugs?:        If you find a problem with this file, send the file and version
;                information (from above) and the problem description to:
;
;                    Internet:    [e-mail]
;                    AppleLink:    APPLE.BUGS
;
;
    IF &TYPE('__FILEMANAGER__') = 'UNDEFINED' THEN
__FILEMANAGER__ SET 1

    IF &TYPE('__FILEMANAGERTYPES__') = 'UNDEFINED' THEN
    include 'FileManagerTypes.a'
    ENDIF
    IF &TYPE('__FILES__') = 'UNDEFINED' THEN
    include 'Files.a'
    ENDIF
    IF &TYPE('__FINDER__') = 'UNDEFINED' THEN
    include 'Finder.a'
    ENDIF
;  You can use FileManager.h or FileManagerSPI.h, but not both
    IF &TYPE('_FILEMANAGERSPI__') = 'UNDEFINED' THEN
    IF FOR_SYSTEM8_PREEMPTIVE THEN
; >>>>>>>>>>>>>>>>>>>>>>>>>>>>> F o u n d a t i o n  D e f i n i t i o n s <<<<<<<<<<<<<<<<<<<<<<<<<<<<<
;
;****************************************************************************
;    CONSTANTS & TYPES
;****************************************************************************
;

kFSInfoInvalidVersion            EQU        0
kFSInfoD10Version                EQU        1
kFSInfoD11Version                EQU        2
kFSInfoCurrentReleasedVersion    EQU        2
; typedef UInt32                         FSInfoVersion


kFSHFSPath                        EQU        1
kFSUnixPath                        EQU        2
kFSDOSPath                        EQU        3
; typedef UInt32                         FSPathnameType


kFSFileIsLocked                    EQU        $00000001
; typedef OptionBits                     FSFileFlags

FSFileInformation        RECORD 0
flags                     ds.l    1                ; offset: $0 (0)
finderInfo                 ds        FInfo            ; offset: $4 (4)
extendedFinderInfo         ds        FXInfo            ; offset: $14 (20)
creationDate             ds        FSDate            ; offset: $24 (36)
modificationDate         ds        FSDate            ; offset: $34 (52)
dataForkSize             ds        FSSize            ; offset: $44 (68)
resourceForkSize         ds        FSSize            ; offset: $4C (76)
sizeof                     EQU *                    ; size:   $54 (84)
                        ENDR
; typedef struct FSFileInformation *    FSFileInformationPtr


kFSFolderIsLocked                EQU        $00000001
; typedef OptionBits                     FSFolderFlags

FSFolderInformation        RECORD 0
flags                     ds.l    1                ; offset: $0 (0)
finderInfo                 ds        DInfo            ; offset: $4 (4)
extendedFinderInfo         ds        DXInfo            ; offset: $14 (20)
creationDate             ds        FSDate            ; offset: $24 (36)
modificationDate         ds        FSDate            ; offset: $34 (52)
sizeof                     EQU *                    ; size:   $44 (68)
                        ENDR
; typedef struct FSFolderInformation *    FSFolderInformationPtr


kFSVolumeIsLockedInHardware        EQU        $00000001
kFSVolumeIsLockedInSoftware        EQU        $00000002
kFSVolumeIsLockedMask            EQU        $00000003
kFSVolumeIsEjectable            EQU        $00000004
kFSVolumeIsOffline                EQU        $00000008
kFSVolumeIsRemote                EQU        $00000010
; typedef OptionBits                     FSVolumeFlags

FSVolumeInformation        RECORD 0
folderInfo                 ds        FSFolderInformation ; offset: $0 (0)
flags                     ds.l    1                ; offset: $44 (68)
totalBytes                 ds        FSSize            ; offset: $48 (72)
freeBytes                 ds        FSSize            ; offset: $50 (80)
constraints                 ds        FSMountAccessConstraints ; offset: $58 (88)
capabilities             ds.l    1                ; offset: $64 (100)
sizeof                     EQU *                    ; size:   $68 (104)
                        ENDR
; typedef struct FSVolumeInformation *    FSVolumeInformationPtr

FSObjectInformation        RECORD 0
objectType                 ds.l    1                ; offset: $0 (0)
fileInfo                 ds        FSFileInformation ; offset: $4 (4)
                         ORG 4
folderInfo                 ds        FSFolderInformation ; offset: $4 (4)
                         ORG 4
volumeInfo                 ds        FSVolumeInformation ; offset: $4 (4)
sizeof                     EQU *                    ; size:   $6C (108)
                        ENDR
; typedef struct FSObjectInformation *    FSObjectInformationPtr

; >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> C O N T A I N E R S <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
;
;****************************************************************************
;    OBJECTS
;****************************************************************************
;
;
;    Function:    FSObjectRefClone
;    Purpose:    Return a copy of an FSObjectRef such that the copy also needs to be disposed.
;    Inputs:
;                object_t        The object ref to be cloned.
;    Outputs:
;                clone_o            Copy of object_t.
;    Notes:
;                The value returned is the same value passed as input in object_t.  This call
;                would typically be used to balance a future call to FSObjectRefDispose.  Some
;                examples where it might be used:
;                    • A called procedure needs to save an FSObjectRef for future use, but the
;                      calling conventions dictate that the caller is responsible for disposing
;                      of the ref.  The called function could call FSObjectRefClone to make its
;                      copy.  The caller can safely dispose of the ref, yet the callee can use
;                      the ref until doing its own dispose.
;                    • In object-oriented programming, an object could be passed an FSObjectRef
;                      in its constructor.  The destructor would be expected to dispose the ref,
;                      but so would the routine that created the object.  FSObjectRefClone could
;                      be used in the constructor.
;
;                The returned FSObjectRef is registered to the calling process (as must object_t).
;
;
; extern OSStatus FSObjectRefClone(FSObjectRef object_t, FSObjectRef *clone_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectRefClone
    ENDIF

;
;    Function:    FSObjectRefDispose
;    Purpose:    Dispose of an FSObjectRef previously returned to a process.
;    Inputs:
;                object_t        The object ref to be disposed.
;    Outputs:
;    Notes:
;                A process must dispose of all FSObjectRefs returned to it.  The FSObjectRefs
;                may be returned as explicit output parameters, or as properties.  If a ref
;                is returned several times for a given object, it must be disposed for each
;                time it was returned.
;
;                When all refs to a given object are disposed, the File Manager will dispose
;                of any resources it allocated in order to operate on that object.  All refs
;                for a process will be automatically disposed upon process termination.
;
;                For refs returned as properties (especially when iterating over muliple
;                objects), the FSObjectRefDisposeBulk call may be more convenient.
;
;
; extern OSStatus FSObjectRefDispose(FSObjectRef object_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectRefDispose
    ENDIF

;
;    Function:    FSObjectFlush
;    Purpose:    Flushes any data cached by the File Manager for the given object.
;    Inputs:
;                object_t        The object to be flushed.
;    Outputs:
;    Notes:
;                If object_t is a file, then any data written to that file (via a stream or backing store,
;                regardless of the process that opened the stream or backing store) will be written by the
;                File Manager to any underlying device.  If object_t is a volume, then any data written to
;                any file on that volume will be flushed.
;
;                Any change to properties of object_t will be flushed (regardless of the object's type).
;
;                Data about the object (or contained in the object) may still reside in the File Manager's
;                caches, but any changes will have been written out by the File Manager.  Note that the
;                underlying device's driver, or the device itself, may cache some data, so the File Manager
;                cannot guarantee that all data has actually been written to the underlying media.
;
;
;
;
;
; extern OSStatus FSObjectFlush(FSObjectRef object_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectFlush
    ENDIF

;
;    Function:    FSObjectRefRegister
;    Purpose:    Allow an FSObjectRef to be used by another process.
;    Inputs:
;                senderObject_t        The object ref.
;                receiverPid_i        The other process that will be using senderObject_t.
;    Outputs:
;    Notes:
;                This call allows one process to send an FSObjectRef to another process
;                such that the other process can use the FSObjectRef itself.  The process
;                specified by receiverPid_i must also dispose of senderObject_t.  The File
;                Manager acts as if senderObject_t has been returned to receiverPid_i.
;
;
;
;
;
;                You might use this call if you have several processes where one process
;                (typically a server of some kind) obtains FSObjectRefs for use by other
;                processes (typically clients of that server).  If the other process (as
;                specified by receiverPid_i) won't actually call the File Manager with
;                that FSObjectRef, then it doesn't need to be registered to that process.
;
;                It would also be possible to have the server process make all of the
;                calls to the File Manager.  FSObjectRefs could still be passed between
;                client and server, but if the clients never use the refs directly, then
;                there would be no need to register the refs to those clients.  (But beware:
;                the server would still be responsible for disposing of all refs returned to
;                it; the server would probably have some cleanup and disposal to do if one
;                of its client processes were to terminate.)
;
;
; extern OSStatus FSObjectRefRegister(FSObjectRef senderObject_t, KernelProcessID receiverPid_i)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectRefRegister
    ENDIF

;
;============================================================================
;    Volume Sets
;============================================================================
;
;
;    Function:    FSVolumeSetGetInformation
;    Purpose:    Returns an FSObjectRef for a Volume Set specified by an
;                FSVolumeSetObjID.
;    Inputs:
;                volumeSet_t                The volume set.
;    Outputs:
;                object_o                Object ref for the volume set.
;                includesBootVolume_o    True if the volume set includes the boot volume.
;    Notes:
;                There is currently only one volume set.  In the future there could be others
;                (perhaps file servers; perhaps to support multiple local users).
;
;
; extern OSStatus FSVolumeSetGetInformation(FSVolumeSetObjID volumeSet_t, Boolean *includesBootVolume_o, FSObjectRef *object_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSVolumeSetGetInformation
    ENDIF

;
;============================================================================
;    Folders
;============================================================================
;
;
;    Function:    FSFolderCreate
;    Purpose:    Create a new named folder within a specified folder
;    Inputs:
;                containerRef_t        The object ref of the parent of the new folder.
;                folderName_i        The name of the new folder as a _persistent_ TextObject.
;    Outputs:
;                folderRef_o            The object ref of the new folder.
;    Notes:
;                An error will be returned if the folder already exists.
;
;
; extern OSStatus FSFolderCreate(FSObjectRef containerRef_t, ConstFSName folderName_i, FSObjectRef *folderRef_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSFolderCreate
    ENDIF

;
;============================================================================
;    Files
;============================================================================
;
;
;    Function:    FSFileCreate
;    Purpose:    Create a new named file within a specified folder
;    Inputs:
;                containerRef_t        The object ref of the parent of the new file.
;                fileName_i            The name of the new file as a _persistent_ TextObject.
;                fileCreator_i        The new file's Finder creator.
;                fileType_i            The new file's Finder type.
;    Outputs:
;                fileRef_o            The object ref of the new file.
;    Notes:
;                An error will be returned if the file already exists.
;
;
; extern OSStatus FSFileCreate(FSObjectRef containerRef_t, ConstFSName fileName_i, OSType fileCreator_i, OSType fileType_i, FSObjectRef *fileRef_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSFileCreate
    ENDIF

;
;============================================================================
;    Folder and File Requests
;============================================================================
;
;
;    Function:    FSObjectDelete
;    Purpose:    Deletes an object.  The FSObjectRef is NOT disposed; you must still dispose it yourself.
;                Further attempts to use the ref will return errors (such as E_ObjectNotFound).
;
;    Inputs:
;                object_t        The object to be deleted.
;    Outputs:
;
;
; extern OSStatus FSObjectDelete(FSObjectRef object_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectDelete
    ENDIF

;
;    Function:    FSObjectMoveRename
;    Purpose:    Move a file or folder to a new folder and (optionally) rename it.
;    Inputs:
;                sourceObjectRef_t    The object ref of the file or folder to move.
;                destContainerRef_i    The object ref of the new parent folder.
;                newObjectName_i        The new name for the moved file or folder (optional).
;    Outputs:
;    Notes:
;                An error will be returned if another file or folder exists in the
;                folder specified by destContainerRef_i which has the same name as
;                sourceObjectRef_t.
;
;
; extern OSStatus FSObjectMoveRename(FSObjectRef sourceObjectRef_t, FSObjectRef destContainerRef_i, ConstFSName newObjectName_i)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectMoveRename
    ENDIF

;
;    Function:    FSObjectRename
;    Purpose:    Rename a file or folder.
;    Inputs:
;                sourceObjectRef_t    The object ref of the file or folder to rename.
;                newObjectName_i        The new name for the file or folder.
;    Outputs:
;    Notes:
;                An error will be returned if another file or folder exists in the
;                same folder as sourceObjectRef_t with the name newObjectName_i.
;
;
; extern OSStatus FSObjectRename(FSObjectRef sourceObjectRef_t, ConstFSName newObjectName_i)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectRename
    ENDIF

; >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> C a p a b i l i t i e s <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
;
;****************************************************************************
;    PROPERTY ACCESS METHODS
;****************************************************************************
;
;
;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;    Object Property Simple Values
;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;
;
;    Function:    FSObjectGetOneProperty
;    Purpose:    Get one property attribute of an object.
;    Inputs:
;                objectRef_t            The object ref.
;                property_i            The property attribute to get.
;                propertySize_i        The size of the property buffer specified
;                                    by propertyValue_o
;    Outputs:
;                property_o            The requested property data.
;    Notes:
;                This function can be used to get the value of a simple property as
;                well as other attributes of all properties such as size, type,
;                state, etc. The attribute to get is specified by
;                property_i->attribute.
;
;                Fork property values must be obtained by using the stream or mapped
;                file access routines.
;
;
; extern OSStatus FSObjectGetOneProperty(FSObjectRef objectRef_t, const FSProperty *property_i, ByteCount propertySize_i, LogicalAddress property_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectGetOneProperty
    ENDIF

;
;    Function:    FSObjectGetInformation
;    Purpose:    Get a predefined aggregate property set for an object.
;    Inputs:
;                objectRef_t            The object ref.
;                infoVersion_i        The version of the FSObjectInformation data record
;                                    specified by objectInfo_o.
;    Outputs:
;                objectInfo_o        The aggregate property data (optional).
;                objectName_o        The name of the specified object (optional).
;    Notes:
;                Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
;                version of the FSObjectInformation record. infoVersion_i is ignored
;                if objectInfo_o is omitted.
;
;                objectName_o, if specified, must reference a preinitialized persistent
;                TextObject of sufficient size to contain the object's name.
;
;
; extern OSStatus FSObjectGetInformation(FSObjectRef objectRef_t, FSInfoVersion infoVersion_i, FSObjectInformation *objectInfo_o, FSName objectName_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectGetInformation
    ENDIF

;
;    Function:    FSObjectGetVolumeInformation
;    Purpose:    Get a predefined aggregate property set for a volume object.
;    Inputs:
;                volumeItemRef_t        The object ref of a file or folder on the volume or
;                                    the volume itself.
;                infoVersion_i        The version of the FSObjectInformation data record
;                                    specified by volumeInfo_o.
;    Outputs:
;                volumeInfo_o        The aggregate volume property data (optional).
;                volumeObjectRef_o    The object ref of the volume (optional).
;                volumeName_o        The name of the volume (optional).
;    Notes:
;                Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
;                version of the FSObjectInformation record. infoVersion_i is ignored
;                if volumeInfo_o is omitted.
;
;                volumeName_o, if specified, must reference a preinitialized persistent
;                TextObject of sufficient size to contain the volume's name.
;
;                This function is functionally equivalent to FSObjectGetInformation when
;                the target object ref is the volume's object ref.
;
;
; extern OSStatus FSObjectGetVolumeInformation(FSObjectRef volumeItemRef_t, FSInfoVersion infoVersion_i, FSObjectInformation *volumeInfo_o, FSObjectRef *volumeObjectRef_o, FSName volumeName_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectGetVolumeInformation
    ENDIF

;
;    Function:    FSObjectSetOneProperty
;    Purpose:    Set one property attribute of an object.
;    Inputs:
;                objectRef_t            The object ref.
;                property_i            The property attribute to set.
;                propertySize_i        The size of the property buffer specified
;                                    by propertyValue_i.
;                propertyData_i        The new property data.
;    Outputs:
;    Notes:
;                Fork property values must be changed by using the stream or mapped
;                file access routines.
;
;
; extern OSStatus FSObjectSetOneProperty(FSObjectRef objectRef_t, const FSProperty *property_i, ByteCount propertySize_i, ConstLogicalAddress propertyData_i)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectSetOneProperty
    ENDIF

;
;============================================================================
;    Stream-based Access Method
;============================================================================
;
;
;    Function:    FSStreamClose
;    Purpose:    Close a stream previously opened with FSStreamOpen or FSStreamOpenWithConstraints.
;    Inputs:
;                stream_t            The stream to close.
;    Outputs:
;    Notes:
;                Any data written to the stream is flushed (written by the File Manager) before the
;                stream is closed.  The FSStreamObjID, stream_t, may no longer be used.  Any resources
;                allocated by the File Manager for use by this stream will be disposed.
;
;
; extern OSStatus FSStreamClose(FSStreamObjID stream_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamClose
    ENDIF

;
;    Function:    FSStreamFlush
;    Purpose:    Any data written to the stream will be written by the File Manager.
;    Inputs:
;                stream_t            The stream to flush.
;    Outputs:
;    Notes:
;                Stream data may still reside in the File Manager's caches, but any changes will have
;                been written out by the File Manager.  Note that the underlying device's driver, or
;                the device itself, may cache some data, so the File Manager cannot guarantee that
;                all data has actually been written to the underlying media.
;
;                Other information about the object (such as its modification date) might not be flushed
;                by this call, though any volume-level data needed to access the stream will be.
;
;
;
;
; extern OSStatus FSStreamFlush(FSStreamObjID stream_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamFlush
    ENDIF

;
;    Function:    FSStreamGetAbsoluteEOF
;    Purpose:    Get the logical end-of-file of an open file fork.
;    Inputs:
;                stream_t            The target stream.
;    Outputs:
;                currentEOF_o        The logical end-of-file of the specified
;                                    stream.
;    Notes:
;
;
; extern OSStatus FSStreamGetAbsoluteEOF(FSStreamObjID stream_t, FSOffset *currentEOF_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamGetAbsoluteEOF
    ENDIF

;
;    Function:    FSStreamGetMark
;    Purpose:    Returns the current mark (position offset) for a stream.
;    Inputs:
;                stream_t            The stream.
;    Outputs:
;                currentMark_o        Current offset in the stream, stream_t.
;    Notes:
;                This call returns the offset from the start of the file that would be
;                equivalent to using a FSForkPositionDescriptor whose positionOffset is
;                0, and whose positionMode is kFSFromMark.  A stream's mark is set to
;                the byte following the last read or write, or via FSStreamSetMark.
;
;
; extern OSStatus FSStreamGetMark(FSStreamObjID stream_t, FSOffset *currentMark_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamGetMark
    ENDIF

;
;    Function:    FSStreamOpen
;    Purpose:    Open a file fork for stream access.
;    Inputs:
;                fileObjectRef_t        The object ref of the file to open.
;                fork_i                The fork to open.
;    Outputs:
;                stream_o            The new stream ID.
;    Notes:
;                The only allowable values for fork_i are kFSDataFork and
;                kFSResourceFork.
;
;                FSStreamOpen attempts to open the fork with exclusive read/write
;                access. If the file is locked or is open on another stream with
;                conflicting access constraints, then an error is returned. Use
;                FSStreamOpenWithConstraints() to specify particular access
;                constratins.
;
;
; extern OSStatus FSStreamOpen(FSObjectRef fileObjectRef_i, FSForkType fork_i, FSStreamObjID *stream_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamOpen
    ENDIF

;
;    Function:    FSStreamSetAbsoluteEOF
;    Purpose:    Set the logical end-of-file of an open file fork.
;    Inputs:
;                stream_t            The target stream.
;                eof_i                The new logical end-of-file of the stream.
;    Outputs:
;    Notes:
;                If there is not enough space on the volume to set the EOF of
;                the fork specified by stream_t to eof_i, then the EOF is not
;                changed and an error is returned.
;
;
; extern OSStatus FSStreamSetAbsoluteEOF(FSStreamObjID stream_t, const FSOffset *eof_i)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamSetAbsoluteEOF
    ENDIF

;
;    Function:    FSStreamSetMark
;    Purpose:    Sets the current mark (position offset) for a stream.
;    Inputs:
;                stream_t            The stream.
;                newPosition_i        The new position of the stream's mark.
;                options_i
;    Outputs:
;                originalMark_o        The stream's mark, before being changed (relative
;                                    to the start of the stream).
;                currentMark_o        The new mark, relative to the start of the stream.
;    Notes:
;                A stream's mark is usually used for sequential access to a stream,
;                or to position relative to the ending position of the last operation
;                on a stream.  This call lets you explicitly set the mark for future
;                operations that will operate relative to the current mark.
;
;                If kFSMarkPinToEOF is set in options_i, and the new position specified
;                by newPosition_i would exceed the current end of the stream (also known
;                as End Of File or EOF), then the mark will be set to the EOF and E_NoError
;                is returned.  Otherwise, an error will returned.  The mark may never be
;                set past the end of the stream.
;
;
;
;
; extern OSStatus FSStreamSetMark(FSStreamObjID stream_t, const FSForkPositionDescriptor *newPosition_i, FSStreamSetMarkOptions options_i, FSOffset *originalMark_o, FSOffset *currentMark_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamSetMark
    ENDIF

;
;    Function:    FSStreamSimpleRead
;    Purpose:    Read data from an open stream.
;    Inputs:
;                stream_t            The target stream.
;                requestLength_i        The number of bytes to read from the fork.
;                position_i            The starting position for the read operation
;
;    Outputs:
;                data_o                The address of a buffer to the read bytes.
;                actualLength_o        The actual number of bytes read from the file (optional).
;                currentMark_o        The mark position within the stream after the
;                                    read operation (optional)
;    Notes:
;                The stream mark is always positioned after the last byte read after all
;                calls to FSStreamSimpleRead().
;
;                If an attempt is made to read beyond the logical EOF of the fork, then
;                the mark is set at the logical EOF of the file, actualLength_o contains
;                the actual number of bytes read, and an error is returned.
;
;
; extern OSStatus FSStreamSimpleRead(FSStreamObjID stream_t, ByteCount requestLength_i, const FSForkPositionDescriptor *position_i, LogicalAddress data_o, ByteCount *actualLength_o, FSOffset *currentMark_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamSimpleRead
    ENDIF

;
;    Function:    FSStreamSimpleWrite
;    Purpose:    Write data to an open stream.
;    Inputs:
;                stream_t            The target stream.
;                requestLength_i        The number of bytes to write to the fork.
;                data_i                The address of a buffer contating the data to write.
;                position_i            The starting position for the write operation
;
;    Outputs:
;                actualLength_o        The actual number of bytes written to the file (optional).
;                currentMark_o        The mark position within the stream after the
;                                    read operation (optional)
;    Notes:
;                The stream mark is always positioned after the last byte written after all
;                calls to FSStreamSimpleWrite().
;
;                If an attempt is made to write beyond the logical EOF of the fork, then
;                the EOF is moved to the byte following the last written byte.
;
;
; extern OSStatus FSStreamSimpleWrite(FSStreamObjID stream_t, ByteCount requestLength_i, ConstLogicalAddress data_i, const FSForkPositionDescriptor *position_i, ByteCount *actualLength_o, FSOffset *currentMark_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSStreamSimpleWrite
    ENDIF

;
;============================================================================
;    Memory-mapped Access Method(Backing Store Requests)
;============================================================================
;
;
;    Function:    FSMappedFileClose
;    Purpose:    Closes an access path to a file used for backing store.
;    Inputs:
;                backingStore_t        The backing store object.
;    Outputs:
;    Notes:
;                Basically the same as FSStreamClose, but for a backing store.
;
;                All data written to this backing store (by writing to pages backed by
;                this store) will be flushed (written) by the File Manager.
;
;
; extern OSStatus FSMappedFileClose(FSBackingStoreObjID backingStore_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSMappedFileClose
    ENDIF

;
;    Function:    FSMappedFileFlush
;    Purpose:    Any data written via the backing store will be written by the File Manager.
;    Inputs:
;                backingStore_t        The backing store to flush.
;    Outputs:
;    Notes:
;                Data may still reside in the File Manager's caches, but any changes will have been
;                written out by the File Manager.  Note that the underlying device's driver, or the
;                device itself, may cache some data, so the File Manager cannot guarantee that all
;                data has actually been written to the underlying media.
;
;                Other information about the object (such as its modification date) might not be flushed
;                by this call, though any volume-level data needed to access the fork data will be.
;
;
; extern OSStatus FSMappedFileFlush(FSBackingStoreObjID backingStore_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSMappedFileFlush
    ENDIF

;
;    Function:    FSMappedFileGetAbsoluteEOF
;    Purpose:    Return the EOF (length) of the fork being accessed by the given backing store.
;    Inputs:
;                backingStore_t        The backing store used to access the fork.
;    Outputs:
;                currentEOF_o        The size, in bytes, of the fork.
;    Notes:
;                Since access to a fork via a backing store (i.e. memory mapped file access) is
;                accomplished by directly accessing memory pages, the virtual memory system must
;                read and write entire pages.  If the last page is modified, the entire page is
;                written, resulting in the fork size being rounded up to a multiple of a page size.
;                Similarly for access to pages beyond the fork's EOF.
;
;                This call returns the current EOF (length) of the underlying fork.  This may be
;                set implicitly by writing to backed pages, or by using the FSMappedFileSetEOF
;                call.  It may also be changed by streams opened to the same fork.
;
;
; extern OSStatus FSMappedFileGetAbsoluteEOF(FSBackingStoreObjID backingStore_t, FSOffset *currentEOF_0)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSMappedFileGetAbsoluteEOF
    ENDIF

;
;    Function:    FSMappedFileOpen
;    Purpose:    Open a file fork for memory mapped access.
;    Inputs:
;                fileObjectRef_t        The object ref of the file to open.
;                fork_i                The fork to open.
;    Outputs:
;                backingStore_o        The backing store used to access the fork.
;    Notes:
;                The only allowable values for fork_i are kFSDataFork and
;                kFSResourceFork.
;
;                FSMappedFileOpen attempts to open the fork with exclusive read/write
;                access. If the file is locked or is open on another stream with
;                conflicting access constraints, then an error is returned. Use
;                FSMappedFileOpenWithConstraints() to specify particular access
;                constratins.
;
;
; extern OSStatus FSMappedFileOpen(FSObjectRef fileObjectRef_t, FSForkType fork_i, FSBackingStoreObjID *backingStore_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSMappedFileOpen
    ENDIF

;
;    Function:    FSMappedFileSetAbsoluteEOF
;    Purpose:    Sets the EOF (length) of the fork being accessed by the given backing store.
;    Inputs:
;                backingStore_t        The backing store used to access the fork.
;                eof_i                The new length (EOF) of the fork.
;    Outputs:
;                currentEOF_o        The new size, in bytes, of the fork.
;    Notes:
;                Since access to a fork via a backing store (i.e. memory mapped file access) is
;                accomplished by directly accessing memory pages, the virtual memory system must
;                read and write entire pages.  If the last page is modified, the entire page is
;                written, resulting in the fork size being rounded up to a multiple of a page size.
;                Similarly for access to pages beyond the fork's EOF.
;
;                This call allows the EOF to be explicitly set for a fork being accessed via a
;                backing store.  Any data beyond the EOF will not actually be written to the fork.
;                The File Manager has no way to detect whether access to pages occurs beyond the
;                EOF; it is a programming error to access bytes beyond the EOF via a backing store.
;
;                This call would typically be used when a fork has been memory mapped to enable
;                convenient access to a file's data structures as if it were completely in memory.
;                You would make all changes to the data structures, then use this call to indicate
;                the number of bytes that are valid and should be written to the fork.
;
;
; extern OSStatus FSMappedFileSetAbsoluteEOF(FSBackingStoreObjID backingStore_t, const FSOffset *eof_i, FSOffset *currentEOF_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSMappedFileSetAbsoluteEOF
    ENDIF

;
;****************************************************************************
;    NAVIGATION & ENUMERATION
;****************************************************************************
;
;
;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;    Object Iteration
;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;
;
;    Function:    FSObjectIterateOnce
;    Purpose:    Iterate to the next object in the current container and get
;                aggregate property information.
;    Inputs:
;                iterator_t                The object iterator.
;                objectInfoVersion_i        The version of the FSObjectInformation data record
;                                        specified by objectInfo_o.
;    Outputs:
;                objectInfo_o            Aggregate property information about the current
;                                        iterator object (optional).
;                objectRef_o                The object ref of the current iterator object (optional).
;                objectName_o            The name of the current iterator object (optional).
;    Notes:
;                Use kFSInfoCurrentReleasedVersion for infoVersion_i to specify the latest
;                version of the FSObjectInformation record. infoVersion_i is ignored
;                if objectInfo_o is omitted.
;
;                objectName_o, if specified, must reference a preinitialized persistent
;                TextObject of sufficient size to contain the object's name.
;
;                If the iterator has reached the end of it's current container, then an
;                exception will be returned.
;
;
; extern OSStatus FSObjectIterateOnce(FSObjectIteratorObjID iterator_t, FSInfoVersion objectInfoVersion_i, FSObjectInformation *objectInfo_o, FSObjectRef *objectRef_o, FSName objectName_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectIterateOnce
    ENDIF

;
;    Function:    FSObjectIteratorChangeCurrentScope
;    Purpose:    Move an object iterator into or out of a container.
;    Inputs:
;                iterator_t        The object iterator.
;                movement_i        The direction to move: into or out of a container.
;    Outputs:
;    Notes:
;                If movement_i is kFSObjectEnter, then the iterator must be positioned on
;                an object that is capable of containing other objects; it does not need to
;                actually contain any objects at that time.  That object will become the new
;                current scope of the iterator and it will be in Start Of Iteration state
;                (meaning that all objects in the current scope have yet to be returned).
;                The iterator will not be positioned on any object.
;
;                If movement_i is kFSObjectExit,  then the current scope will become the object
;                that contains the current scope; the iterator's new position will be the object
;                that was the current scope.  If the current scope and the outermost scope were
;                the same, then the outermost scope will also change to the new current scope and
;                E_ExitIteratorScope is returned (so that you realize you will be iterating outside
;                of the scope that you used to create the iterator; the iterator remains usable).
;
;                Object iterators keep track of all of the objects between the outermost scope and
;                the current scope (this is known as the "scope stack").  If any object in the scope
;                stack is moved, the iterator is invalidated and will return the error
;                E_IteratorScopeException until it has been explicitly fixed (by FSObjectIteratorRecreate)
;                or disposed.  This call adds or removes objects from the scope stack.
;
;
; extern OSStatus FSObjectIteratorChangeCurrentScope(FSObjectIteratorObjID iterator_t, FSObjectIteratorMovement movement_i)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectIteratorChangeCurrentScope
    ENDIF

;
;    Function:    FSObjectIteratorCreate
;    Purpose:    Create an iterator for iterating over objects.
;    Inputs:
;                outermostScope_t        The initial outermost scope and current scope.
;                options_i                Controls whether the iterator will traverse objects in
;                                        a single container or all embedded (nested) containers.
;                                        Also controls which kinds of objects will be returned.
;    Outputs:
;                iterator_o                The object iterator.
;    Notes:
;                The outermost scope and current scope of the iterator are set to outermostScope_t.
;                The iterator is not positioned on any object, though it is inside outermostScope_t.
;                OutermostScope_t must be an object capable of containing other objects (such as the
;                Universe, a volume set, a volume, or a folder).  The iterator is put into "Start Of
;                Iteration" state, meaning that all objects in the current scope have yet to be
;                returned.
;
;                The File Manager allocates resources and maintains state for every iterator.  When
;                you have finished using an iterator, you should call FSObjectIteratorDispose to dispose
;                of it.
;
;
; extern OSStatus FSObjectIteratorCreate(FSObjectRef outermostScope_t, FSObjectIteratorCreationOptions options_i, FSObjectIteratorObjID *iterator_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectIteratorCreate
    ENDIF

;
;    Function:    FSObjectIteratorDispose
;    Purpose:    Dispose of an object iterator.
;    Inputs:
;                iterator_t        The object iterator.
;    Outputs:
;    Notes:
;                The File Manager will dispose of the iterator and release any resources
;                allocated to the iterator.  Further attempts to use the iterator will result
;                in an error.
;
;
;
;
; extern OSStatus FSObjectIteratorDispose(FSObjectIteratorObjID iterator_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectIteratorDispose
    ENDIF

;
;    Function:    FSObjectIteratorRestart
;    Purpose:    Place an object iterator in the Start Of Iterator state, in its current scope.
;    Inputs:
;                iterator_t        The object iterator.
;    Outputs:
;    Notes:
;                The iterator is not positioned on any object.  The iterator is put into "Start Of
;                Iteration" state, meaning that all objects in the current scope have yet to be
;                returned.
;
;                You would use this call to completely restart iteration within the current scope,
;                ignoring any state about objects previously returned in the current scope.  The
;                outermost scope is not affected.  State information about which objects have been
;                returned from scopes outside the current scope is unchanged.
;
;
; extern OSStatus FSObjectIteratorRestart(FSObjectIteratorObjID iterator_t)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectIteratorRestart
    ENDIF

;
;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;    Object Resolution
;++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
;
;
;    Function:    FSObjectCreateRef
;    Purpose:    Get the object ref for a named object in a given container.
;    Inputs:
;                container_i                The object container ref.
;                objectName_i            The name of the target object.
;    Outputs:
;                objectRef_o                The resulting object ref.
;    Notes:
;
;
; extern OSStatus FSObjectCreateRef(FSObjectRef container_i, ConstFSName objectName_i, FSObjectRef *objectRef_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectCreateRef
    ENDIF

;
;    Function:    FSObjectExchange
;    Purpose:    Exchange the properties of two objects.  Typically used for "safe
;                saving", while maintaining an object's persistent reference.
;    Inputs:
;                object1_i        One object.
;                object2_i        The object to exchange it with.
;    Outputs:
;    Notes:
;                This call is used to allow a "safe save" that preserves an object's
;                persistent reference.  For example, you might want to save an updated
;                set of properties to an object so that any errors while saving result
;                in the object being unchanged; but, you also want the object's persistent
;                reference to remain unchanged (so that things like aliases still work).
;
;                What you would do is create a second object somewhere (in a temporary
;                folder, for example).  Write out all of the properties, both unchanged
;                and changed, to the second object.  When done saving, you would call
;                FSObjectExchange with both objects; the contents of the two objects get
;                swapped in such a way that the original object has the new properties,
;                but retains its old persistent reference.
;
;
;
;
; extern OSStatus FSObjectExchange(FSObjectRef object1_i, FSObjectRef object2_i)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectExchange
    ENDIF

;
;    Function:    FSObjectGetContainerRef
;    Purpose:    Get the object ref for the container of a given object.
;    Inputs:
;                objectRef_i                The object of interest.
;    Outputs:
;                containerRef_o            The object ref of the container of
;                                        containerRef_o.
;    Notes:
;
;
; extern OSStatus FSObjectGetContainerRef(FSObjectRef objectRef_i, FSObjectRef *containerRef_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectGetContainerRef
    ENDIF

;
;    Function:    FSObjectRefGetFSSpec
;    Purpose:    Return an FSSpec for an object (suitable for use with the Files API).
;    Inputs:
;                object_t            The object.
;    Outputs:
;                fSSpec_o            An FSSpec that specifies the same object as object_t,
;                                    suitable for use with the Files API.
;    Notes:
;                This call is intended to be used by code that is required to use both the
;                Files API and the FileManager API (or has clients that use both APIs).
;                For example, a piece of code may already exist with an API that uses FSSpecs,
;                but has been converted internally to use the FSObjectRefs; it would use this
;                call to produce an FSSpec as an output for the pre-existing API.
;
;                It would be best to provide an API that allows its clients to use FSObjectRefs.
;
;
; extern OSStatus FSObjectRefGetFSSpec(FSObjectRef object_t, FSSpec *fSSpec_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectRefGetFSSpec
    ENDIF

;
;
; extern OSStatus FSPathnameResolve(FSObjectRef container_i, const char *path_i, ByteCount pathLength_i, FSPathnameType pathType_i, FSObjectRef *objectRef_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSPathnameResolve
    ENDIF

;
;    Function:    FSSpecGetFSObjectRef
;    Purpose:    Return an FSObjectRef for an object specified via an FSSpec.
;    Inputs:
;                theFSSpec_t            An FSSpec for the object.
;    Outputs:
;                theObject_o            An FSObjectRef for the object.
;    Notes:
;                This call is intended to be used by code that is required to use both the
;                Files API and the FileManager API (or has clients that use both APIs).
;                For example, a piece of code may already exist with an API that uses FSSpecs,
;                but has been converted internally to use the FSObjectRefs; it would use this
;                call to take an input FSSpec and convert it to an FSObjectRef to use internally;
;                the FSObjectRef would then be disposed before completing the call.
;
;                It would be best to provide an API that allows its clients to use FSObjectRefs.
;
;
; extern OSStatus FSSpecGetFSObjectRef(const FSSpec *theFSSpec_t, FSObjectRef *theObject_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSSpecGetFSObjectRef
    ENDIF

;
;    Function:    FSVolumeGetInformation
;    Purpose:    Get the volume object ref for a given volume object ID.
;    Inputs:
;                volume_t        The volume's object ID.
;    Outputs:
;                object_o        The volume's object ref.
;    Notes:
;
;
; extern OSStatus FSVolumeGetInformation(FSVolumeObjID volume_t, FSObjectRef *object_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSVolumeGetInformation
    ENDIF

;
; extern OSStatus FSObjectGetOnePropertySize(FSObjectRef objectRef_t, const FSProperty *property_i, FSSize *propertySize_o)
;
    IF GENERATINGCFM THEN
        IMPORT_CFM_FUNCTION FSObjectGetOnePropertySize
    ENDIF

    ENDIF
    ENDIF
    ENDIF ; __FILEMANAGER__